<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Cauchy-Lorentz Distribution</title>
<link rel="stylesheet" href="../../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Math Toolkit 4.2.1">
<link rel="up" href="../dists.html" title="Distributions">
<link rel="prev" href="binomial_dist.html" title="Binomial Distribution">
<link rel="next" href="chi_squared_dist.html" title="Chi Squared Distribution">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="binomial_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="chi_squared_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="math_toolkit.dist_ref.dists.cauchy_dist"></a><a class="link" href="cauchy_dist.html" title="Cauchy-Lorentz Distribution">Cauchy-Lorentz
        Distribution</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">cauchy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span>
          <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a>   <span class="special">=</span> <a class="link" href="../../pol_ref/pol_ref_ref.html" title="Policy Class Reference">policies::policy&lt;&gt;</a> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">cauchy_distribution</span><span class="special">&lt;&gt;</span> <span class="identifier">cauchy</span><span class="special">;</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../../policy.html" title="Chapter 22. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">cauchy_distribution</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
   <span class="keyword">typedef</span> <span class="identifier">RealType</span>  <span class="identifier">value_type</span><span class="special">;</span>
   <span class="keyword">typedef</span> <span class="identifier">Policy</span>    <span class="identifier">policy_type</span><span class="special">;</span>

   <span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>

   <span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
   <span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
<span class="special">};</span>
</pre>
<p>
          The <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
          distribution</a> is named after Augustin Cauchy and Hendrik Lorentz.
          It is a <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">continuous
          probability distribution</a> with <a href="http://en.wikipedia.org/wiki/Probability_distribution" target="_top">probability
          distribution function PDF</a> given by:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../equations/cauchy_ref1.svg"></span>

          </p></blockquote></div>
<p>
          The location parameter <span class="emphasis"><em>x<sub>0</sub></em></span> is the location of the peak
          of the distribution (the mode of the distribution), while the scale parameter
          γ specifies half the width of the PDF at half the maximum height. If the
          location is zero, and the scale 1, then the result is a standard Cauchy
          distribution.
        </p>
<p>
          The distribution is important in physics as it is the solution to the differential
          equation describing forced resonance, while in spectroscopy it is the description
          of the line shape of spectral lines.
        </p>
<p>
          The following graph shows how the distributions moves as the location parameter
          changes:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf1.svg" align="middle"></span>

          </p></blockquote></div>
<p>
          While the following graph shows how the shape (scale) parameter alters
          the distribution:
        </p>
<div class="blockquote"><blockquote class="blockquote"><p>
            <span class="inlinemediaobject"><img src="../../../../graphs/cauchy_pdf2.svg" align="middle"></span>

          </p></blockquote></div>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h0"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.member_functions"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.member_functions">Member
          Functions</a>
        </h5>
<pre class="programlisting"><span class="identifier">cauchy_distribution</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">location</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">RealType</span> <span class="identifier">scale</span> <span class="special">=</span> <span class="number">1</span><span class="special">);</span>
</pre>
<p>
          Constructs a Cauchy distribution, with location parameter <span class="emphasis"><em>location</em></span>
          and scale parameter <span class="emphasis"><em>scale</em></span>. When these parameters take
          their default values (location = 0, scale = 1) then the result is a Standard
          Cauchy Distribution.
        </p>
<p>
          Requires scale &gt; 0, otherwise calls <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>.
        </p>
<pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">location</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
          Returns the location parameter of the distribution.
        </p>
<pre class="programlisting"><span class="identifier">RealType</span> <span class="identifier">scale</span><span class="special">()</span><span class="keyword">const</span><span class="special">;</span>
</pre>
<p>
          Returns the scale parameter of the distribution.
        </p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h1"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.non_member_accessors"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.non_member_accessors">Non-member
          Accessors</a>
        </h5>
<p>
          All the <a class="link" href="../nmp.html" title="Non-Member Properties">usual non-member accessor
          functions</a> that are generic to all distributions are supported:
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.cdf">Cumulative Distribution Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.pdf">Probability Density Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.quantile">Quantile</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.hazard">Hazard Function</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.chf">Cumulative Hazard Function</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.median">median</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mode">mode</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.range">range</a> and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.support">support</a>.
        </p>
<p>
          Note however that the Cauchy distribution does not have a mean, standard
          deviation, etc. See <a class="link" href="../../pol_ref/assert_undefined.html" title="Mathematically Undefined Function Policies">mathematically
          undefined function</a> to control whether these should fail to compile
          with a BOOST_STATIC_ASSERTION_FAILURE, which is the default.
        </p>
<p>
          Alternately, the functions <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.mean">mean</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.sd">standard deviation</a>,
          <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.variance">variance</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.skewness">skewness</a>, <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis">kurtosis</a>
          and <a class="link" href="../nmp.html#math_toolkit.dist_ref.nmp.kurtosis_excess">kurtosis_excess</a>
          will all return a <a class="link" href="../../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a>
          if called.
        </p>
<p>
          The domain of the random variable is [-[max_value], +[min_value]].
        </p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h2"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.accuracy"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.accuracy">Accuracy</a>
        </h5>
<p>
          The Cauchy distribution is implemented in terms of the standard library
          <code class="computeroutput"><span class="identifier">tan</span></code> and <code class="computeroutput"><span class="identifier">atan</span></code>
          functions, and as such should have very low error rates.
        </p>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h3"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.implementation"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.implementation">Implementation</a>
        </h5>
<p>
          In the following table x<sub>0 </sub> is the location parameter of the distribution,
          γ is its scale parameter, <span class="emphasis"><em>x</em></span> is the random variate,
          <span class="emphasis"><em>p</em></span> is the probability and <span class="emphasis"><em>q = 1-p</em></span>.
        </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Function
                  </p>
                </th>
<th>
                  <p>
                    Implementation Notes
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    pdf
                  </p>
                </td>
<td>
                  <p>
                    Using the relation: <span class="emphasis"><em>pdf = 1 / (π * γ * (1 + ((x - x<sub>0 </sub>)
                    / γ)<sup>2</sup>) </em></span>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    cdf and its complement
                  </p>
                </td>
<td>
                  <p>
                    The cdf is normally given by:
                  </p>
                  <div class="blockquote"><blockquote class="blockquote"><p>
                      <span class="serif_italic">p = 0.5 + atan(x)/π</span>
                    </p></blockquote></div>
                  <p>
                    But that suffers from cancellation error as x -&gt; -∞. So recall
                    that for <code class="computeroutput"><span class="identifier">x</span> <span class="special">&lt;</span>
                    <span class="number">0</span></code>:
                  </p>
                  <div class="blockquote"><blockquote class="blockquote"><p>
                      <span class="serif_italic">atan(x) = -π/2 - atan(1/x)</span>
                    </p></blockquote></div>
                  <p>
                    Substituting into the above we get:
                  </p>
                  <div class="blockquote"><blockquote class="blockquote"><p>
                      <span class="serif_italic">p = -atan(1/x) ; x &lt; 0</span>
                    </p></blockquote></div>
                  <p>
                    So the procedure is to calculate the cdf for -fabs(x) using the
                    above formula. Note that to factor in the location and scale
                    parameters you must substitute (x - x<sub>0 </sub>) / γ for x in the above.
                  </p>
                  <p>
                    This procedure yields the smaller of <span class="emphasis"><em>p</em></span> and
                    <span class="emphasis"><em>q</em></span>, so the result may need subtracting from
                    1 depending on whether we want the complement or not, and whether
                    <span class="emphasis"><em>x</em></span> is less than x<sub>0 </sub> or not.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    quantile
                  </p>
                </td>
<td>
                  <p>
                    The same procedure is used irrespective of whether we're starting
                    from the probability or its complement. First the argument <span class="emphasis"><em>p</em></span>
                    is reduced to the range [-0.5, 0.5], then the relation
                  </p>
                  <div class="blockquote"><blockquote class="blockquote"><p>
                      <span class="serif_italic">x = x<sub>0 </sub> ± γ / tan(π * p)</span>
                    </p></blockquote></div>
                  <p>
                    is used to obtain the result. Whether we're adding or subtracting
                    from x<sub>0 </sub> is determined by whether we're starting from the complement
                    or not.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    mode
                  </p>
                </td>
<td>
                  <p>
                    The location parameter.
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<h5>
<a name="math_toolkit.dist_ref.dists.cauchy_dist.h4"></a>
          <span class="phrase"><a name="math_toolkit.dist_ref.dists.cauchy_dist.references"></a></span><a class="link" href="cauchy_dist.html#math_toolkit.dist_ref.dists.cauchy_dist.references">References</a>
        </h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <a href="http://en.wikipedia.org/wiki/Cauchy_distribution" target="_top">Cauchy-Lorentz
              distribution</a>
            </li>
<li class="listitem">
              <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm" target="_top">NIST
              Exploratory Data Analysis</a>
            </li>
<li class="listitem">
              <a href="http://mathworld.wolfram.com/CauchyDistribution.html" target="_top">Weisstein,
              Eric W. "Cauchy Distribution." From MathWorld--A Wolfram
              Web Resource.</a>
            </li>
</ul></div>
</div>
<div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="binomial_dist.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../dists.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="chi_squared_dist.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
